retour
(a detour
Fork)
(Fork of original detour-rs that works on nightly after nightly-2022-11-07)
This is a cross-platform detour library developed in Rust. Beyond the basic functionality, this library handles branch redirects, RIP-relative instructions, hot-patching, NOP-padded functions, and allows the original function to be called using a trampoline whilst hooked.
This is one of few cross-platform detour libraries that exists, and to maintain this feature, not all desired functionality can be supported due to lack of cross-platform APIs. Therefore EIP relocation is not supported.
NOTE: Nightly is currently required for static_detour!
and is enabled with the static-detour
feature flag.
Platforms
This library provides CI for these targets:
- Linux
i686-unknown-linux-gnu
x86_64-unknown-linux-gnu
x86_64-unknown-linux-musl
- Windows
i686-pc-windows-gnu
i686-pc-windows-msvc
x86_64-pc-windows-gnu
x86_64-pc-windows-msvc
- macOS
i686-apple-darwin
x86_64-apple-darwin
Installation
Add this to your Cargo.toml
:
[]
# `static-detour` feature requires nightly
= { = "0.3", = ["static-detour"] }
Example
- A static detour (one of three different detours):
use Error;
use static_detour;
static_detour!
- A Windows API hooking example is available here; build it by running:
$ cargo +nightly build --features="static-detour" --example messageboxw_detour
- A non-nightly example using GenericDetour can be found here; build it by running:
$ cargo build --example kernel32_detour
Mentions
This is fork of the original detour-rs creator darfink that put so much work into the original crate.
Part of the library's external user interface was inspired by minhook-rs, created by Jascha-N, and it contains derivative code of his work.
Injection Methods
This crate provides the ability to hook functions in other applications, but does not provide the utilities necessary for injecting/attaching to another process. If you're looking for ways to inject your hooking library here are some approaches you can look into:
- dll injection libraries such as dll-syringe
- LD_PRELOAD on *nix platforms
- Various debuggers, including x64dbg and Cheat Engine
Appendix
-
EIP relocation
Should be performed whenever a function's prolog instructions are being executed, simultaneously as the function itself is being detoured. This is done by halting all affected threads, copying the affected instructions and appending a
JMP
to return to the function. This is barely ever an issue, and never in single-threaded environments, but YMMV. -
NOP-padding
int // xor eax, eax // ret // nop // nop // ...
Functions such as this one, lacking a hot-patching area, and too small to be hooked with a 5-byte
jmp
, are supported thanks to the detection of code padding (NOP/INT3
instructions). Therefore the required amount of trailingNOP
instructions will be replaced, to make room for the detour.